home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / include / dev / pdev.new.h < prev    next >
C/C++ Source or Header  |  1989-06-01  |  13KB  |  332 lines
  1. /*
  2.  * pdev.h --
  3.  *
  4.  *    Declarations of the kernel/user-level-server interface for
  5.  *    pseudo-devices. A pseudo-device is a file
  6.  *    whose semantics are implemented by a user-level server process.
  7.  *    All other processes act on the file normally.  Their operations
  8.  *    on the file are mapped by the kernel into a request-response
  9.  *    exchange with the server process.  The types and constants defined
  10.  *    here are needed by the server programs to implement their
  11.  *    half of the pseudo-device protocol.  As well as implement the
  12.  *    regular file operations, Fs_Read, Fs_Write, and Fs_IOControl,
  13.  *    the server is involved in open/close time actions, and the
  14.  *    server helps control the select state of the pseudo device.
  15.  *    
  16.  *    A more complete explaination of pseudo-devices should be in
  17.  *    the man page (/sprite/doc/ref/devices/pdev), but the following
  18.  *    brief explaination may help.  The interface between the kernel
  19.  *    and the server process is based on filesystem streams.  The
  20.  *    server gets a "control stream" when it opens the pseudo-device
  21.  *    file with the FS_MASTER flag.  This control stream is readable
  22.  *    when a new client process has opened the pseudo-device.  The
  23.  *    control stream contains a short message with a new filesystem
  24.  *    streamID for a "service stream" that the server uses to communicate
  25.  *    with the new client.
  26.  *    Service streams are used by the server to get request messages
  27.  *    (that correspond to client operations) and return results.
  28.  *
  29.  *    Associated with each service stream is a "request buffer".  The server
  30.  *    gets request messages from clients indirectly; the requests are
  31.  *    placed into the request buffer, along with their data, and the server
  32.  *    learns about new requests by reading messages from the service stream
  33.  *    that contain 'firstByte' and 'lastByte' offsets into the request buffer.
  34.  *    This buffered interface lets the kernel stack up many requests (writes,
  35.  *    in particular) before a    context switch is required to the server
  36.  *    program.  Of course, this also lets the server handle all the queued
  37.  *    requests at one time.  When the    server has handled requests it updates
  38.  *    the 'firstByte' pointer by making a IOC_PDEV_SET_PTRS ioctl() on
  39.  *    the service stream.
  40.  *
  41.  *    There can also be a read ahead buffer associated with each service
  42.  *    stream.  This is filled with data by the server program that is to
  43.  *    be read by a client, and the kernel moves data from this buffer,
  44.  *    which is again in the server's address space, to the client without
  45.  *    having to switch out to the server process. 
  46.  *    
  47.  * Copyright 1987 Regents of the University of California
  48.  * All rights reserved.
  49.  * Permission to use, copy, modify, and distribute this
  50.  * software and its documentation for any purpose and without
  51.  * fee is hereby granted, provided that the above copyright
  52.  * notice appear in all copies.  The University of California
  53.  * makes no representations about the suitability of this
  54.  * software for any purpose.  It is provided "as is" without
  55.  * express or implied warranty.
  56.  *
  57.  *
  58.  * $Header: /sprite/src/lib/include/dev/RCS/pdev.h,v 1.14 89/03/13 08:58:35 brent Exp Locker: brent $ SPRITE (Berkeley)
  59.  */
  60.  
  61. #ifndef _PDEV
  62. #define _PDEV
  63.  
  64. #include "proc.h"
  65. #include "fs.h"
  66. #ifdef KERNEL
  67. #include "fsIO.h"
  68. #else
  69. #include <kernel/fsIO.h>
  70. #endif
  71.  
  72. /*
  73.  * Pseudo-device operations
  74.  *    PDEV_OPEN        The first request after a client open.
  75.  *    PDEV_DUP        OBSOLETE, but might resurrect itself.
  76.  *    PDEV_CLOSE        The last request.
  77.  *    PDEV_READ        Read data from the pseudo-device.
  78.  *    PDEV_WRITE        Write data to the pseudo-device.
  79.  *    PDEV_IOCTL        Special operation on the pseudo-device.
  80.  *    PDEV_WRITE_ASYNC    Asynchronous write.  No reply needed.
  81.  *
  82.  * These two only apply to pseudo-device connections to pseudo-file-systems.
  83.  * For regular pseudo-devices the kernel takes care of attribute handling.
  84.  *    PDEV_GET_ATTR        Get attributes given a pdev connection.
  85.  *    PDEV_SET_ATTR        Set attributes given a pdev connection.
  86.  */
  87.  
  88. typedef int Pdev_Op;
  89.  
  90. #define PDEV_OPEN        1
  91. /* #define PDEV_DUP        2 */
  92. #define PDEV_CLOSE        3
  93. #define PDEV_READ        4
  94. #define PDEV_WRITE        5
  95. #define PDEV_IOCTL        6
  96. #define PDEV_WRITE_ASYNC    7
  97. #define PDEV_GET_ATTR        8
  98. #define PDEV_SET_ATTR        9
  99.  
  100. /*
  101.  * A pseudo-device server gets a 'control stream' when opening a pseudo-device.
  102.  * The following structure describes the messages read from the control stream.
  103.  * Control stream messages are used to notify the server that it
  104.  * has a new private stream because a client opened the pseudo-device.
  105.  */
  106. typedef struct Pdev_Notify {
  107.     unsigned int    magic;            /* == PDEV_NOTIFY_MAGIC */
  108.     int            newStreamID;
  109.     int            reserved;        /* Extra */
  110. } Pdev_Notify;
  111.  
  112. #define PDEV_NOTIFY_MAGIC    0x1D4E4F52
  113.  
  114. /*
  115.  * The first message on a private stream is a PDEV_OPEN.
  116.  * This message identifies the client process, its host, and the host's
  117.  * byte order to the server.
  118.  */
  119.  
  120. typedef struct Pdev_OpenParam {
  121.     int flags;            /* Flags from the Fs_Open call */
  122.     Proc_PID pid;        /* Client's process ID */
  123.     int hostID;            /* Host ID where client is from */
  124.     int uid;            /* User ID of the client process */
  125.     int gid;            /* Group ID of the client process */
  126.     int byteOrder;        /* Byte order identifier */
  127.     int reserved;        /* Extra */
  128. } Pdev_OpenParam;
  129.  
  130. /*
  131.  * PDEV_READ, PDEV_WRITE request parameters, see <kernel/fsIO.h>
  132.  */
  133.  
  134. typedef Fs_IOParam Pdev_RWParam;
  135.  
  136. /*
  137.  * PDEV_IOCTL request parameter, see <kernel/fsIO.h>
  138.  */
  139.  
  140. typedef Fs_IOCParam Pdev_IOCParam;
  141.  
  142. /*
  143.  * PDEV_SET_ATTR request parameters.  These are in the Pdev_Request header,
  144.  * and the new Fs_Attributes record is passed as the data block following
  145.  * the header.  The user and group ID are used for authentication.
  146.  */
  147.  
  148. typedef struct {
  149.     int        flags;        /* Which attributes to set */
  150.     int        uid;        /* User ID */
  151.     int        gid;        /* Group ID */
  152. } Pdev_SetAttrParam;
  153.  
  154.  
  155. /*
  156.  * When a client does something to the pseudo-device the server gets
  157.  * a corresponding request message.  The structure of it is defined here.
  158.  * The control information in the request header is the same for both
  159.  * pseudo-device and pseudo-filesystem operations.
  160.  */
  161.  
  162. typedef struct {
  163.     unsigned int magic;        /* PDEV_REQUEST_MAGIC or PFS_REQUEST_MAGIC */
  164.     Pdev_Op    operation;    /* What action is requested. */
  165.     int        messageSize;    /* The complete size of the request header
  166.                  * plus data, plus padding for alignment */
  167.     int        requestSize;    /* Size of data following this header */
  168.     int        replySize;    /* Max size of the reply data expected. */
  169.     int        dataOffset;    /* Offset of data from start of header */
  170. } Pdev_RequestHdr;
  171.  
  172. typedef struct {
  173.     Pdev_RequestHdr    hdr;    /* with PDEV_REQUEST_MAGIC */
  174.     union {            /* Additional parameters to the operation. */
  175.     Pdev_OpenParam        open;
  176.     Pdev_RWParam        read;
  177.     Pdev_RWParam        write;
  178.     Pdev_IOCParam        ioctl;
  179.     Pdev_SetAttrParam    setAttr;
  180.     } param;
  181. } Pdev_Request;
  182.  
  183. #define PDEV_REQUEST_MAGIC    0x7265717E
  184.  
  185. /*
  186.  * IOC_PDEV_REPLY is used to return the following information about
  187.  * a reply to a client's request.  The status in
  188.  * the reply header will be the return value of the client's system call,
  189.  * except for FS_WOULD_BLOCK and FS_LOOKUP_REDIRECT which are processed
  190.  * by the kernel.
  191.  */
  192.  
  193. typedef struct Pdev_Reply {
  194.     unsigned int magic;        /* PDEV_REPLY_MAGIC */
  195.     ReturnStatus status;    /* Return status of remote call */
  196.     int        selectBits;    /* Return select state bits */
  197.     int        replySize;    /* Size of the data in replyBuf, if any */
  198.     Address    replyBuf;    /* Server space address of reply data */
  199.     int        signal;        /* Signal to return, if non-zero */
  200.     int        code;        /* Code to modify signal */
  201. } Pdev_Reply;
  202.  
  203. #define PDEV_REPLY_MAGIC    0x52455057
  204.  
  205. /*
  206.  * IOC_PDEV_SMALL_REPLY uses the following struct to return a small
  207.  * amount of data to the client's request.
  208.  * Up to PDEV_SMALL_DATA_LIMIT bytes can be returned.
  209.  * 
  210.  */
  211. #define PDEV_SMALL_DATA_LIMIT    16
  212.  
  213. typedef struct Pdev_ReplyData {
  214.     unsigned int magic;        /* PDEV_REPLY_DATA_MAGIC */
  215.     ReturnStatus status;    /* Return status of remote call */
  216.     int        selectBits;    /* Return select state bits */
  217.     int        replySize;    /* Size of following data */
  218.     Address    replyBuf;    /* Unused, needed for padding & compatibility */
  219.     int        signal;        /* (non-zero) Signal to generate, if any */
  220.     int        code;        /* Code to modify the signal */
  221.     char    data[PDEV_SMALL_DATA_LIMIT];    /* Reply data */
  222. } Pdev_ReplyData;
  223.  
  224. #define PDEV_REPLY_DATA_MAGIC    0x524ABC57
  225.  
  226. /*
  227.  * I/O Controls for server streams.
  228.  *    IOC_PDEV_READY        The server uses this to notify the kernel
  229.  *                that the pseudo-device is ready for I/O now.
  230.  *                The input buffer should contain an int
  231.  *                with an or'd combination of FS_READABLE,
  232.  *                FS_WRITABLE, or FS_EXCEPTION.
  233.  *    IOC_PDEV_SET_BUF    These are used to tell the kernel where the
  234.  *                request buffer and read ahead buffer (if any)
  235.  *                are. The input buffer should contain a
  236.  *                Pdev_SetBufArgs struct.  Note that this
  237.  *                needs to be done after getting a notification
  238.  *                on the control stream before any request
  239.  *                (i.e. the client's open request) comes through.
  240.  *                This can also be done later to change the
  241.  *                buffer if needed.  The buffer change takes
  242.  *                place as soon as the previous one empties.
  243.  *                The switch is indicated by the requestAddr
  244.  *                that you read from the service stream.
  245.  *    IOC_PDEV_WRITE_BEHIND    Set (Unset) write-behind buffering in the
  246.  *                request buffer.  The single input argument
  247.  *                is a pointer to a Boolean; TRUE enables
  248.  *                write-behind, FALSE inhibits it.  The default
  249.  *                is no write-behind.
  250.  *    IOC_PDEV_SET_PTRS    These are used to update the firstByte and
  251.  *                lastByte pointers into the request and
  252.  *                read ahead buffers.  The input buffer
  253.  *                is a Pdev_BufPtrs structure.
  254.  *    IOC_PDEV_REPLY        This is used to send a reply to a request.
  255.  *                The input buffer contains a Pdev_Reply.  This
  256.  *                includes an address (in the server's space)
  257.  *                of a buffer containing reply data, if any.
  258.  *    IOC_PDEV_SMALL_REPLY    This is like IOC_PDEV_REPLY, except that
  259.  *                the reply data is embedding in the struct
  260.  *                passed into the kernel.  The amount of data
  261.  *                that can be returned this was is defined
  262.  *                by PDEV_SMALL_DATA_LIMIT.
  263.  *    IOC_PDEV_BIG_WRITES    Set (Unset) the ability of the client to
  264.  *                write a chunk larger than will fit into
  265.  *                the request buffer.  This is to support
  266.  *                UDP socket semantics that prevent a client
  267.  *                from writing more than the declared packet size.
  268.  *                (Of course, we could do better by keeping the
  269.  *                 existing semantics that automatically break
  270.  *                 the write into smaller ones...)
  271.  *                The input buffer should reference a Boolean;
  272.  *                TRUE enables big writes (which is the default)
  273.  *                FALSE prevents big writes.
  274.  *    IOC_PDEV_SIGNAL_OWNER    This sends a signal to the controlling process
  275.  *                of the pseudo-device.  If there is no owner
  276.  *                then this is ignored.  The input buffer contains
  277.  *                the signal number and code to send.
  278.  *
  279.  */
  280.  
  281. #define IOC_PDEV        (2 << 16)
  282. #define IOC_PDEV_READY        (IOC_PDEV | 0x1)
  283. #define IOC_PDEV_SET_BUF    (IOC_PDEV | 0x2)
  284. #define IOC_PDEV_WRITE_BEHIND    (IOC_PDEV | 0x3)
  285. #define IOC_PDEV_SET_PTRS    (IOC_PDEV | 0x4)
  286. #define IOC_PDEV_REPLY        (IOC_PDEV | 0x5)
  287. #define IOC_PDEV_BIG_WRITES    (IOC_PDEV | 0x6)
  288. #define IOC_PDEV_SIGNAL_OWNER    (IOC_PDEV | 0x7)
  289. #define IOC_PDEV_SMALL_REPLY    (IOC_PDEV | 0x8)
  290.  
  291. /*
  292.  * Input structure for the IOC_PDEV_SET_BUF IOControl
  293.  */
  294.  
  295. typedef struct Pdev_SetBufArgs {
  296.     Address    requestBufAddr;        /* Server's address of request buffer */
  297.     int        requestBufSize;        /* Num bytes in the request buffer */
  298.     Address    readBufAddr;        /* NULL if no read ahead.  Non-NULL
  299.                      * implicitly enables read-ahead. */
  300.     int        readBufSize;        /* Num bytes in the read ahead buffer */
  301. } Pdev_SetBufArgs;
  302.  
  303. /*
  304.  * Input structure for IOC_PDEV_SET_PTRS IOControl.
  305.  */
  306.  
  307. typedef struct Pdev_BufPtrs {
  308.     int magic;            /* == PDEV_BUF_PTR_MAGIC */
  309.     Address    requestAddr;    /* The address of the request buffer.  This is
  310.                  * valid when reading only, and it indicates
  311.                  * what request buffer is being used.  See
  312.                  * IOC_PDEV_SET_BUF. */
  313.     int requestFirstByte;    /* Byte offset of the first valid data byte
  314.                  * in the request buffer.  If -1 buf is empty */
  315.     int requestLastByte;    /* Byte offset of the last valid data byte. */
  316.     int readFirstByte;        /* Byte offset of the first valid data byte
  317.                  * in the read ahead buffer. -1 => empty */
  318.     int readLastByte;        /* Byte offset of the last data byte. */
  319. } Pdev_BufPtrs;
  320.  
  321. #define PDEV_BUF_PTR_MAGIC    0x3C46DF14
  322.  
  323. /*
  324.  * Stucture for the IOC_PDEV_SIGNAL_OWNER operation.
  325.  */
  326. typedef struct Pdev_Signal {
  327.     unsigned int signal;
  328.     unsigned int code;
  329. } Pdev_Signal;
  330.  
  331. #endif _PDEV
  332.